Explaining programs reliably

Science isaboutflndingbetter explanations [3],andto dosoitisguidedby ‰sthetics, such asOccam’sRazor, anda conviction thatrealit y isflxed.Incomputerscience,instead, we buildtheobjects we explain, andwe changethem.Computerscience, then,isaboutflnding betterexplanations forthingsthatcanbe changedto helpimprovetheexplanations. A allthemetresofpapercomputerbooksshow,thereisa highdemandeven forconventional explanations, tosay nothingofthereliable, timelyand parsimonious explanations | often innovelformats| required by usersofembeddedsystems,such asflghterpilots . Computerscien tists writeprogramsandexplain programs| whethertodocumentthemforotherprogrammers,toexplain them inthecomputerscience literature,ortowritemanualsorhelpforusers.Allthese activities nvolve manualinterv ention,typically using wordprocessors: whenpossible improvementsarespotted,theauthororauthorsrevise thedocuments.Since allthedocumentsina particular p ojectarerelated, a lotoftextinthevarious documentsissimilar ifnot exactly thesame. Elsewhere we have discussed writing bettermanuals forusers[1,6,7];wehavealsodiscussed theuseful impactofqualit y explanation programminglanguage design[12]and on physical devicedesign[14].Inthis paper,we areconcerned withwriting betterexplanationsforprograms. ProgramsareusuallywritteninplainASCII text but documentationusuallyhasa specialform. Ifa WYSIWYG wordprocessor isused,programcodementioned needsediting toflxthefont,alignmen t,pointsize andsoon;ifamark-uplanguage (lik eHTML orLTEX) isused,thenvarious programsymbolsneedconverting tothemark-uplanguage’s conventionsothattheycan appearproperly . Forexample,thesymbol& hastobe editedto&forHTML orto\& forLTEX | and ofcoursethismark-upisno longervalidinprograms, soaccurate conversion todocumentation cannotreadily beconflrmedwitha compiler. Thus,typically ,a fragmen t ofprogramcode iscutand-pasted froma workingprogramintothedocumentation, anditisthenedited carefully toconformtothe documentation system’s requiremen ts(andtothetypographical requiremen ts,particularly linelengthandindentation). Laterachangeismade,say,intheprogram. Butthisistheflrstofseveralchangesanticipated, soit perhapsisn’t worthgoingtothetrouble ofcutting-andpasting-and-editing again.Ma ybeitseemseasier totry toduplicate changesinthepreviously prepared text? Ifthereisany hurdletomakingchanges,eventually notallofthemwillbemade.Managingdocumentsand programsisnormallysuch hardworkthateither improvementsdo notgetmade,orchangesdo getmade (say tothedocumentation) butarenotaccurately re°ectedeverywherelse(say intheprogram). Forexample,thedocumentation mightreadbetterifa name is changed...thisisthethinendofthewedge,andasubtlethreatointegrit y.Reliable writing hastobemade soeasythatthereisnevera temptation toavoidimprovingbothcodeanddocumentation consisten tly .For onceevena fewdiscrepancies accummulate, itbecomes an evenharderexercise torestore integrit y. To ensuredocuments are reliable, despitebeing editedby hand,itmakessensetosharecommon text asm uch aspossible automatically . Apartfromgeneratinghighqualit y documents,thekeyidea,then,isto make itveryeasytokeeptogether andmaintainwhat arenormally separate | andsometimes increasingly independent!| documents.Shared textshouldonlybe edite d inoneplac e. Variousolutions tothisproblem have beenproposed,and allhave considerable advantagesoverapproac hingtheprocessmanually . Literate programmingwasintroducedby Knuth[5, 11]tocombineprogramsand theirdocumentationto createreadable programs.Numerousprogramshave beenpreparedusingliterate programming:sizable examplesincludeKnuth’sown outstanding books [4]. Thereisno duplication feither code ordocumentation:literate programminginterlea vestheminoneflle,